home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / djgpp / tktdoc / daemons.doc < prev    next >
Encoding:
Text File  |  1994-08-11  |  7.1 KB  |  249 lines
  1. NETWORK DAEMONS PROGRAMMING REFERENCE
  2.  
  3. In order for the DESQview/X Network Manager to
  4. process certain service requests, a "daemon" (that is, unseen)
  5. process may be started to handle the request. This section describes
  6. the programming interface provided for developers to create these
  7. network daemons.
  8.  
  9. To configure the DESQview/X Network Manager to
  10. use a new daemon, see the "Adding Network Daemons" section
  11. for details.
  12.  
  13. Note that network daemons use the Berkeley
  14. Socket Interface to communicate with the DESQview/X Network
  15. Manager (see Chapter 8: The Berkeley Socket Library for
  16. details). In addition, DESQview/X supplies extension routines to facilitate
  17. the creation of new daemons.
  18.  
  19. Daemon Types
  20.  
  21. There are two type of daemons that may be created for use in a DESQview/X
  22. system - regular and lingering daemons:
  23.  
  24. Regular
  25.  
  26. Regular daemons are started by the Network
  27. Manager, process the supplied request and then terminate immediately.
  28.  
  29. Lingering
  30.  
  31. A lingering daemon will also processes a supplied request, but instead
  32. of terminating immediately, "lingers" for a specified period of time
  33. in anticipation of another service request.  If no service request is
  34. accepted by the Network Manager before the linger time expires,
  35. the daemon is terminated.
  36.  
  37. Note that each daemon type may appear in one of two flavors - the
  38. daemon may be a TCP (stream) daemon or a UDP (datagram)
  39. daemon.
  40.  
  41. General Operation
  42.  
  43. The interaction between the Network Manager and
  44. a network daemon is as follows:
  45.  
  46. The Network Manager accepts a request
  47. for a particular service that has a daemon associated with it.
  48.  
  49. If the daemon is not currently running, the Network Manager instructs
  50. DESQview/X to start the daemon and passes the service request to it.
  51.  
  52. For daemons already running, the Network Manager forwards the service
  53. request directly to the daemon.
  54.  
  55. When the daemon has processed the request, it either terminates or
  56. lingers for a specified period of time.
  57.  
  58. Adding Network Daemons
  59.  
  60. Adding new daemons to the DESQview/X Network Manager is relatively
  61. straight forward--place the DVP file of the daemon into the network
  62. subdirectory and run the DESQview/X setup program.
  63.  
  64. Note, however, if the daemon uses a new type of service that is not
  65. specified in the SERVICES file, this file must be edited manually
  66. to describe the service.
  67.  
  68. When you select the Enable/Disable Services option on the Advanced
  69. Network screen, Setup will scan the DVP files present in the network
  70. directory and present the Program Name fields of the DVP files to
  71. the user. Any service that is elected will have a corresponding service
  72. line added to the INETD.CFG file.
  73.  
  74. Anatomy of a Daemon
  75.  
  76. In order to facilitate the communication between the DESQview/X Network
  77. Manager and a daemon, DESQview/X supplies extension
  78. routines (listed at the end of this section). The most important of
  79. these routines is the so_daemon call. This encapsulates a lot of
  80. handshaking and passing of parameters  between the Network Manager
  81. and the daemon and frees the daemon writer from the tedium of
  82. performing multiple initialization routines.
  83.  
  84. A regular daemon will normally use the so_daemon and so_exitdaemon
  85. routines by following this model:
  86.  
  87. #include "sys\socket.h"
  88. void main(int argc,char *argv[])
  89. {
  90.   int s;
  91.  
  92.   /* ... main work ... */
  93.  
  94.   if((s = so_daemon(argv,FALSE)) >= 0) {
  95.      perform_bsd_socket_work();
  96.      so_close(s);  /* for
  97.  
  98. TCP daemons ... or ... */
  99.  
  100.      so_unlink(s); /* for
  101.  
  102. UDP daemons */
  103.  
  104.      }
  105.      so_exitdaemon();
  106. }
  107.  
  108. A lingering daemon will normally use the so_daemon and so_exitdaemon
  109. routines by following this model:
  110.  
  111. #include "sys\socket.h"
  112. void main(int argc,char *argv[])
  113. {
  114.   int s;
  115.  
  116.   /* ... main loop ... */
  117.  
  118.   while (1) {
  119.      if((s = so_daemon(argv,TRUE)) < 0)
  120.      continue;
  121.      perform_bsd_socket_work();
  122.      so_close(s);  /* for
  123.  
  124. TCP daemons ... or ... */
  125.  
  126.      so_unlink(s); /* for
  127.  
  128. UDP daemons */
  129.  
  130.      }
  131.  }
  132.  
  133. Note that the so_daemon routine handles the linger time for the daemon
  134. and will terminate the daemon if it is exceeded.
  135.  
  136. Differences between TCP and UDP Daemons
  137.  
  138. There are several differences between a TCP and a UDP daemon that
  139. should be noted.
  140.  
  141. A TCP daemon will use the so_close routine to close a socket.
  142.  
  143. A UDP daemon must use the so_unlink extension routine to release
  144. a socket. This is because UDP daemons are handed a child socket
  145. that was generated when a request for the service was made. Closing
  146. the socket with so_close would prevent further requests for that
  147. service from being processed by the Network Manager.
  148.  
  149. A TCP daemon will use TCP I/O primitives, such as recv and send in
  150. the main body of the daemon (perform_bsd_socket_work) to perform
  151. the required communication.
  152.  
  153. A UDP daemon will use UDP I/O primitives, such as recvfrom
  154. and sendto in the main body of the daemon (perform_bsd_socket_work)
  155. to perform the required communication.
  156.  
  157. Daemon Routines
  158.  
  159. The DESQview/X extension routines that enable network daemons to be
  160. created with a minimum of effort are listed below in reference form:
  161.  
  162.  so_daemon
  163.  
  164. Synopsis
  165.  
  166. #include <sys\socket.h>
  167. int so_daemon(char *args[], char wait);
  168.  
  169. Description
  170.  
  171. The so_daemon
  172. call is the linkup call for DESQview/X daemon processes. The call
  173. retrieves the connection information for the next connection to be
  174. processed by the daemon. The args parameter must be the arguments
  175. passed to the application upon entry by the C runtime library. Setting
  176. the wait parameter to false allows the daemon to poll for additional
  177. connections or datagrams, while continuing to process current connections.
  178.  
  179.  
  180. As implied above,  the call can be made for daemons of both type SOCK_STREAM
  181. and SOCK_DGRAM. For SOCK_STREAM daemons, the socket descriptor returned
  182. can be processed normally and closed with a standard so_close
  183. call.  For SOCK_DGRAM daemons, the descriptor is a datagram
  184. descriptor ready to make a recvfrom call. The descriptor should then
  185. be closed via the so_unlink call.
  186.  
  187. When the wait parameter is positive, the so_daemon
  188. call will perform all of the duties of determining the proper linger
  189. period and exiting when the time spent waiting for the next request
  190. exceeds the specified wait value.
  191.  
  192. Notes
  193.  
  194. DESQview/X extension call.
  195.  
  196. Return Values
  197.  
  198. so_daemon returns
  199. a non-negative socket descriptor on success and -1 on failure.
  200.  
  201.  so_exitdaemon
  202.  
  203. Synopsis
  204.  
  205. #include <sys\socket.h>
  206. void so_exitdaemon(void);
  207.  
  208. Description
  209.  
  210. The so_exitdaemon
  211. call should be made before the daemon process terminates. This will
  212. allow the socket interface to be uninitialized correctly.
  213.  
  214. Notes
  215.  
  216. DESQview/X extension call.
  217.  
  218.  so_unlink
  219.  
  220. Synopsis
  221.  
  222. #include <sys\socket.h>
  223. int so_unlink(int s);
  224.  
  225. Description
  226.  
  227. The so_unlink
  228. call returns ownership of a daemon socket to the DESQview/X Network
  229. Manager. This call is provided for SOCK_DGRAM type sockets so as to
  230. allow them to be reused after termination of a daemon process.
  231. This call must be used in place of the so_close call for datagram
  232. daemons.
  233.  
  234. Notes
  235.  
  236. DESQview/X extension call.
  237.  
  238. Return Values
  239.  
  240. so_unlink returns
  241. 0 on success, -1 on failure (errno as described below).
  242.  
  243. Errors
  244.  
  245. ENOTSOCK
  246.  
  247. Invalid descriptor.
  248.  
  249.